/*
 * Copyright (c) 1999, 2000, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package javax.naming.directory;

import javax.naming.NamingException;

/**
 * This exception is thrown when an attempt is
 * made to add, or remove, or modify an attribute, its identifier,
 * or its values that conflicts with the attribute's (schema) definition
 * or the attribute's state.
 * It is thrown in response to DirContext.modifyAttributes().
 * It contains a list of modifications that have not been performed, in the
 * order that they were supplied to modifyAttributes().
 * If the list is null, none of the modifications were performed successfully.
 * <p>
 * An AttributeModificationException instance is not synchronized
 * against concurrent multithreaded access. Multiple threads trying
 * to access and modify a single AttributeModification instance
 * should lock the object.
 *
 * @author Rosanna Lee
 * @author Scott Seligman
 * @see DirContext#modifyAttributes
 * @since 1.3
 */

/*
  *<p>
  * The serialized form of an AttributeModificationException object
  * consists of the serialized fields of its NamingException
  * superclass, followed by an array of ModificationItem objects.
  *
*/


public class AttributeModificationException extends NamingException {

  /**
   * Contains the possibly null list of unexecuted modifications.
   *
   * @serial
   */
  private ModificationItem[] unexecs = null;

  /**
   * Constructs a new instance of AttributeModificationException using
   * an explanation. All other fields are set to null.
   *
   * @param explanation Possibly null additional detail about this exception. If null, this
   * exception has no detail message.
   * @see java.lang.Throwable#getMessage
   */
  public AttributeModificationException(String explanation) {
    super(explanation);
  }

  /**
   * Constructs a new instance of AttributeModificationException.
   * All fields are set to null.
   */
  public AttributeModificationException() {
    super();
  }

  /**
   * Sets the unexecuted modification list to be e.
   * Items in the list must appear in the same order in which they were
   * originally supplied in DirContext.modifyAttributes().
   * The first item in the list is the first one that was not executed.
   * If this list is null, none of the operations originally submitted
   * to modifyAttributes() were executed.
   *
   * @param e The possibly null list of unexecuted modifications.
   * @see #getUnexecutedModifications
   */
  public void setUnexecutedModifications(ModificationItem[] e) {
    unexecs = e;
  }

  /**
   * Retrieves the unexecuted modification list.
   * Items in the list appear in the same order in which they were
   * originally supplied in DirContext.modifyAttributes().
   * The first item in the list is the first one that was not executed.
   * If this list is null, none of the operations originally submitted
   * to modifyAttributes() were executed.
   *
   * @return The possibly null unexecuted modification list.
   * @see #setUnexecutedModifications
   */
  public ModificationItem[] getUnexecutedModifications() {
    return unexecs;
  }

  /**
   * The string representation of this exception consists of
   * information about where the error occurred, and
   * the first unexecuted modification.
   * This string is meant for debugging and not mean to be interpreted
   * programmatically.
   *
   * @return The non-null string representation of this exception.
   */
  public String toString() {
    String orig = super.toString();
    if (unexecs != null) {
      orig += ("First unexecuted modification: " +
          unexecs[0].toString());
    }
    return orig;
  }

  /**
   * Use serialVersionUID from JNDI 1.1.1 for interoperability
   */
  private static final long serialVersionUID = 8060676069678710186L;
}
